IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/g_man/cat3/OpenGL/glubuild2dmipmaps.z/glubuild2dmipmaps

Text File | 2002-10-03 | 22.5 KB | 199 lines

gggglllluuuuBBBBuuuuiiiilllldddd2222DDDDMMMMiiiippppmmmmaaaappppssss((((3333GGGG))))          OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee          gggglllluuuuBBBBuuuuiiiilllldddd2222DDDDMMMMiiiippppmmmmaaaappppssss((((3333GGGG))))



NNNNAAAAMMMMEEEE
     gggglllluuuuBBBBuuuuiiiilllldddd2222DDDDMMMMiiiippppmmmmaaaappppssss - builds a two-dimensional mipmap


CCCC SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
     GLint gggglllluuuuBBBBuuuuiiiilllldddd2222DDDDMMMMiiiippppmmmmaaaappppssss( GLenum _t_a_r_g_e_t,
                              GLint _i_n_t_e_r_n_a_l_F_o_r_m_a_t,
                              GLsizei _w_i_d_t_h,
                              GLsizei _h_e_i_g_h_t,
                              GLenum _f_o_r_m_a_t,
                              GLenum _t_y_p_e,
                              const void *_d_a_t_a )


PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
     _t_a_r_g_e_t          Specifies the target texture.  Must be GGGGLLLL____TTTTEEEEXXXXTTTTUUUURRRREEEE____2222DDDD.

     _i_n_t_e_r_n_a_l_F_o_r_m_a_t  Requests the internal storage format of the texture
                     image.  Must be 1, 2, 3, 4, or one of the following
                     symbolic constants:  GGGGLLLL____AAAALLLLPPPPHHHHAAAA, GGGGLLLL____AAAALLLLPPPPHHHHAAAA4444, GGGGLLLL____AAAALLLLPPPPHHHHAAAA8888,
                     GGGGLLLL____AAAALLLLPPPPHHHHAAAA11112222, GGGGLLLL____AAAALLLLPPPPHHHHAAAA11116666, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE4444,
                     GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE8888, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE11112222, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE11116666,
                     GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE____AAAALLLLPPPPHHHHAAAA, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE4444____AAAALLLLPPPPHHHHAAAA4444,
                     GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE6666____AAAALLLLPPPPHHHHAAAA2222, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE8888____AAAALLLLPPPPHHHHAAAA8888,
                     GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE11112222____AAAALLLLPPPPHHHHAAAA4444, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE11112222____AAAALLLLPPPPHHHHAAAA11112222,
                     GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE11116666____AAAALLLLPPPPHHHHAAAA11116666, GGGGLLLL____IIIINNNNTTTTEEEENNNNSSSSIIIITTTTYYYY, GGGGLLLL____IIIINNNNTTTTEEEENNNNSSSSIIIITTTTYYYY4444,
                     GGGGLLLL____IIIINNNNTTTTEEEENNNNSSSSIIIITTTTYYYY8888, GGGGLLLL____IIIINNNNTTTTEEEENNNNSSSSIIIITTTTYYYY11112222, GGGGLLLL____IIIINNNNTTTTEEEENNNNSSSSIIIITTTTYYYY11116666, GGGGLLLL____RRRRGGGGBBBB,
                     GGGGLLLL____RRRR3333____GGGG3333____BBBB2222, GGGGLLLL____RRRRGGGGBBBB4444, GGGGLLLL____RRRRGGGGBBBB5555, GGGGLLLL____RRRRGGGGBBBB8888, GGGGLLLL____RRRRGGGGBBBB11110000,
                     GGGGLLLL____RRRRGGGGBBBB11112222, GGGGLLLL____RRRRGGGGBBBB11116666, GGGGLLLL____RRRRGGGGBBBBAAAA, GGGGLLLL____RRRRGGGGBBBBAAAA2222, GGGGLLLL____RRRRGGGGBBBBAAAA4444,
                     GGGGLLLL____RRRRGGGGBBBB5555____AAAA1111, GGGGLLLL____RRRRGGGGBBBBAAAA8888, GGGGLLLL____RRRRGGGGBBBB11110000____AAAA2222, GGGGLLLL____RRRRGGGGBBBBAAAA11112222 or
                     GGGGLLLL____RRRRGGGGBBBBAAAA11116666.

     _w_i_d_t_h, _h_e_i_g_h_t   Specifies in pixels the width and height, respectively,
                     of the texture image.

     _f_o_r_m_a_t          Specifies the format of the pixel data.  Must be one of
                     GGGGLLLL____CCCCOOOOLLLLOOOORRRR____IIIINNNNDDDDEEEEXXXX, GGGGLLLL____DDDDEEEEPPPPTTTTHHHH____CCCCOOOOMMMMPPPPOOOONNNNEEEENNNNTTTT, GGGGLLLL____RRRREEEEDDDD, GGGGLLLL____GGGGRRRREEEEEEEENNNN,
                     GGGGLLLL____BBBBLLLLUUUUEEEE, GGGGLLLL____AAAALLLLPPPPHHHHAAAA, GGGGLLLL____RRRRGGGGBBBB, GGGGLLLL____RRRRGGGGBBBBAAAA, GGGGLLLL____BBBBGGGGRRRR, GGGGLLLL____BBBBGGGGRRRRAAAA,
                     GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE, or GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE____AAAALLLLPPPPHHHHAAAA.

     _t_y_p_e            Specifies the data type for _d_a_t_a.  Must be one of
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE, GGGGLLLL____BBBBYYYYTTTTEEEE, GGGGLLLL____BBBBIIIITTTTMMMMAAAAPPPP, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT,
                     GGGGLLLL____SSSSHHHHOOOORRRRTTTT, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT, GGGGLLLL____IIIINNNNTTTT, GGGGLLLL____FFFFLLLLOOOOAAAATTTT,
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE____3333____3333____2222, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE____2222____3333____3333____RRRREEEEVVVV,
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____6666____5555, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____6666____5555____RRRREEEEVVVV,
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____4444____4444____4444____4444, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____4444____4444____4444____4444____RRRREEEEVVVV,
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____5555____5555____1111, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____1111____5555____5555____5555____RRRREEEEVVVV,
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____8888____8888____8888____8888, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____8888____8888____8888____8888____RRRREEEEVVVV,
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____11110000____11110000____11110000____2222, or
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____2222____11110000____11110000____11110000____RRRREEEEVVVV.





                                                                        PPPPaaaaggggeeee 1111






gggglllluuuuBBBBuuuuiiiilllldddd2222DDDDMMMMiiiippppmmmmaaaappppssss((((3333GGGG))))          OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee          gggglllluuuuBBBBuuuuiiiilllldddd2222DDDDMMMMiiiippppmmmmaaaappppssss((((3333GGGG))))



     _d_a_t_a            Specifies a pointer to the image data in memory.



DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     gggglllluuuuBBBBuuuuiiiilllldddd2222DDDDMMMMiiiippppmmmmaaaappppssss builds a series of prefiltered two-dimensional texture
     maps of decreasing resolutions called a mipmap. This is used for the
     antialiasing of texture-mapped primitives.

     A return value of zero indicates success, otherwise a GLU error code is
     returned (see gggglllluuuuEEEErrrrrrrroooorrrrSSSSttttrrrriiiinnnngggg).

     Initially, the _w_i_d_t_h and _h_e_i_g_h_t of _d_a_t_a are checked to see if they are a
     power of 2. If not, a copy of _d_a_t_a (not _d_a_t_a), is scaled up or down to
     the nearest power of 2. This copy will be used for subsequent mipmapping
     operations described below. (If _w_i_d_t_h or _h_e_i_g_h_t is exactly between powers
     of 2, then the copy of _d_a_t_a will scale upwards.)  For example, if _w_i_d_t_h
     is 57 and _h_e_i_g_h_t is 23 then a copy of _d_a_t_a will scale up to 64 in _w_i_d_t_h
     and down to 16 in depth, before mipmapping takes place.

     Then, proxy textures (see ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee2222DDDD) are used to determine if the
     implementation can fit the requested texture. If not, both dimensions are
     continually halved until it fits. (If the OpenGL version is _< 1.0, both
     maximum texture dimensions are clamped to the value returned by
     ggggllllGGGGeeeettttIIIInnnntttteeeeggggeeeerrrrvvvv with the argument GGGGLLLL____MMMMAAAAXXXX____TTTTEEEEXXXXTTTTUUUURRRREEEE____SSSSIIIIZZZZEEEE.)

     Next, a series of mipmap levels is built by decimating a copy of _d_a_t_a in
     half along both dimensions until size 1 x 1 is reached. At each level,
     each texel in the halved mipmap level is an average of the corresponding
     four texels in the larger mipmap level. (In the case of rectangular
     images, the decimation will ultimately reach an N x 1 or 1 x N
     configuration. Here, two texels are averaged instead.)

     ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee2222DDDD is called to load each of these mipmap levels.  Level 0 is a
     copy of _d_a_t_a.  The highest level is log(max(width,height)).  For
     example, if _w_i_d_t_h is 64 and _h_e_i_g_h_t is 16 and the implementation can store
     a texture of this size, the following mipmap levels are built: 64 x 16,
     32 x 8, 16 x 4, 8 x 2, 4 x 1, 2 x 1 and 1 x 1. These correspond to levels
     0 through 6, respectively.

     See the ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee1111DDDD reference page for a description of the acceptable
     values for _f_o_r_m_a_t parameter. See the ggggllllDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss reference page for a
     description of the acceptable values for _t_y_p_e parameter.

NNNNOOOOTTTTEEEESSSS
     Note that there is no direct way of querying the maximum level. This can
     be derived indirectly via ggggllllGGGGeeeettttTTTTeeeexxxxLLLLeeeevvvveeeellllPPPPaaaarrrraaaammmmeeeetttteeeerrrr. First, query for the
     width and height actually used at level 0.  (The width and height may not
     be equal to _w_i_d_t_h and _h_e_i_g_h_t respectively since proxy textures might have
     scaled them to fit the implementation.)  Then the maximum level can be
     derived from the formula log(max(_w_i_d_t_h,_h_e_i_g_h_t)).




                                                                        PPPPaaaaggggeeee 2222






gggglllluuuuBBBBuuuuiiiilllldddd2222DDDDMMMMiiiippppmmmmaaaappppssss((((3333GGGG))))          OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee          gggglllluuuuBBBBuuuuiiiilllldddd2222DDDDMMMMiiiippppmmmmaaaappppssss((((3333GGGG))))



NNNNOOOOTTTTEEEESSSS
     Formats GGGGLLLL____BBBBGGGGRRRR, and GGGGLLLL____BBBBGGGGRRRRAAAA, and types GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE____3333____3333____2222,
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE____2222____3333____3333____RRRREEEEVVVV, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____6666____5555,
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____6666____5555____RRRREEEEVVVV, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____4444____4444____4444____4444,
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____4444____4444____4444____4444____RRRREEEEVVVV, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____5555____5555____1111,
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____1111____5555____5555____5555____RRRREEEEVVVV, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____8888____8888____8888____8888,
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____8888____8888____8888____8888____RRRREEEEVVVV, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____11110000____11110000____11110000____2222, and
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____2222____11110000____11110000____11110000____RRRREEEEVVVV are only available if the GL version is
     1.2 or greater and if the GLU version is 1.3 or greater.

EEEERRRRRRRROOOORRRRSSSS
     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE is returned if _w_i_d_t_h, or _h_e_i_g_h_t is < 1.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____EEEENNNNUUUUMMMM is returned if _i_n_t_e_r_n_a_l_F_o_r_m_a_t, _f_o_r_m_a_t, or _t_y_p_e is not
     legal.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is returned if _t_y_p_e is GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE____3333____3333____2222 or
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE____2222____3333____3333____RRRREEEEVVVV and _f_o_r_m_a_t is not GGGGLLLL____RRRRGGGGBBBB.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is returned if _t_y_p_e is GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____6666____5555 or
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____6666____5555____RRRREEEEVVVV and _f_o_r_m_a_t is not GGGGLLLL____RRRRGGGGBBBB.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is returned if _t_y_p_e is GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____4444____4444____4444____4444 or
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____4444____4444____4444____4444____RRRREEEEVVVV and _f_o_r_m_a_t is neither GGGGLLLL____RRRRGGGGBBBBAAAA nor GGGGLLLL____BBBBGGGGRRRRAAAA.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is returned if _t_y_p_e is GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____5555____5555____1111 or
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____1111____5555____5555____5555____RRRREEEEVVVV and _f_o_r_m_a_t is neither GGGGLLLL____RRRRGGGGBBBBAAAA nor GGGGLLLL____BBBBGGGGRRRRAAAA.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is returned if _t_y_p_e is GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____8888____8888____8888____8888 or
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____8888____8888____8888____8888____RRRREEEEVVVV and _f_o_r_m_a_t is neither GGGGLLLL____RRRRGGGGBBBBAAAA nor GGGGLLLL____BBBBGGGGRRRRAAAA.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is returned if _t_y_p_e is GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____11110000____11110000____11110000____2222
     or GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____2222____11110000____11110000____11110000____RRRREEEEVVVV and _f_o_r_m_a_t is neither GGGGLLLL____RRRRGGGGBBBBAAAA nor
     GGGGLLLL____BBBBGGGGRRRRAAAA.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     ggggllllDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss, ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee1111DDDD, ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee2222DDDD, ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee3333DDDD,
     gggglllluuuuBBBBuuuuiiiilllldddd1111DDDDMMMMiiiippppmmmmaaaappppssss, gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppssss, gggglllluuuuEEEErrrrrrrroooorrrrSSSSttttrrrriiiinnnngggg, ggggllllGGGGeeeettttTTTTeeeexxxxIIIImmmmaaaaggggeeee,
     ggggllllGGGGeeeettttTTTTeeeexxxxLLLLeeeevvvveeeellllPPPPaaaarrrraaaammmmeeeetttteeeerrrr, gggglllluuuuBBBBuuuuiiiilllldddd1111DDDDMMMMiiiippppmmmmaaaappppLLLLeeeevvvveeeellllssss, gggglllluuuuBBBBuuuuiiiilllldddd2222DDDDMMMMiiiippppmmmmaaaappppLLLLeeeevvvveeeellllssss,
     gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppLLLLeeeevvvveeeellllssss















                                                                        PPPPaaaaggggeeee 3333